The Atari Compendium/The Atari Compendium (Toad Computers) (1994).iso/files/umich/telecomm/fnordadl/fn132src.zoo/ref-man/shells.tex

Text File | 1991-09-02 | 12.5 KB | 262 lines

@comment Tell Emacs to use -*-texinfo-*- mode
@comment $Id: shells.tex,v 2.2 91/09/01 23:04:43 royce Exp $

@node Shells vs. the Desktop, File Transfers, Anti-Ruggie Measures, Top
@chapter Shells vs. the Desktop
@cindex Shells vs. the desktop

On the Atari ST, the standard environment is the @sc{gem} Desktop (that
screen full of disk drive icons, windows, pull-down menus and so on).  But
one may also choose to run the system by means of a ``shell'' or ``@sc{cli}''
(which stands for Command Line Interface).  Instead of double-clicking on
an icon to run a program, you type its name; instead of dragging icons
around to copy files, you type a command like @samp{cp file1 file2}; et cetera.
In this Chapter, we'll discuss how the choice of desktop vs. shell affects
the operation of Fnordadel.

From day one, the Citadel system has been designed around the
command-line style of operation, and Fnordadel hasn't changed this;
most programs in the distribution take arguments on the command line to
determine their behaviour.  This is antithetical to the mouse-driven,
interactive philosophy of @sc{gem}, but it doesn't mean that you can't run
Fnordadel from the desktop.  You just have to kludge things around a
bit.

@node Running from the Desktop, Running from a Shell, Shells vs. the Desktop, Shells vs. the Desktop
@section Running from the Desktop
@cindex Desktop, running Fnordadel from
@cindex Running from the desktop

There are a few things you need to know.  Firstly, all the
programs in the distribution come with a @file{.tos} extender.  As with standard
ST usage, this means that the programs use no @sc{gem} features of any
kind---just @sc{tos}.  (As an aside: someone once suggested that we graft a
@sc{gem} front-end onto @code{citadel}.  His body hasn't surfaced yet.).

So, what this means for desktop users is that double-clicking on a
Fnordadel program will simply launch the program; the program will not
be supplied with any command-line arguments.  For some programs, this is
@pindex citadel
fine, but for others, notably @code{citadel}, it isn't.  The solution?
Rename the programs to which you would like to supply arguments to
@samp{@var{program}.ttp}.  Now when you run them from the desktop,
a dialogue box will
pop up asking for the command line arguments to be supplied.  Type them
and hit @samp{<CR>} (or click on @samp{OK}) to launch the program.

This doesn't entirely solve the problem, because complex programs
like @code{citadel} can take far more parameters than can be fit into the small
space provided by the @sc{gem} @code{.ttp} parameter dialogue box.  Also,
the @sc{gem} dialogue
converts all the parameters you type into upper-case before giving them to the
program.  This is a Bad Thing if the program in question is expecting
lower-case values.  Fortunately, we've tried to eliminate this problem in all
Fnordadel programs by not checking case with parameters.

There are companies that make enhancement or replacement products for
the @sc{gem} Desktop, such as NeoDesk 3 by Gribnif Software and Hotwire by CodeHead
Software.  Some of these products replace the normal @sc{gem} parameter dialogue
with one that will accept more parameters, or doesn't convert them to
upper-case, or both.  It might be worth your while to investigate some of these
products if you're having trouble using Fnordadel to its fullest, but like
working in a graphical, mouse-oriented environment.  (We have never used any
of these products ourselves, so we're unable to recommend them.  However, if
you try them out and find them useful, let us know how and why so we can record
that fact in future versions of this manual.)

We've tried to make all of the programs in the Fnordadel
distribution decently desktop-friendly.  (Or, at least, not as blindingly
unfriendly as before.)  They can detect when they have been run from the
desktop, and will always prompt you to ``hit any key'' before they exit.
@pindex clog
@pindex popular
For programs like @code{clog}, @code{popular}, et cetera, this is a lifesaver.
(Note that this ``hit any key'' business is only from the desktop; if you
run a Fnordadel program from a shell, or from a door within Fnordadel,
or whatever, it won't do this.)

@node A desktop trick,  , Running from the Desktop, Running from the Desktop
@subheading A desktop trick

A trick that used to be popular back in the days when people ran
ST Citadels on tiny one-drive systems was to fool the ST into thinking
you had two drives, in the following manner:
@enumerate
@item
Arrange your files so that all of your startup
stuff (@code{auto} folder, @file{configur.tos}, @file{citadel.tos}, et cetera)
is on a disk marked ``A'',
and all of your @sc{bbs} data files are on a disk marked ``B''.
@item
Edit
@file{ctdlcnfg.sys} to point @code{#msgdir}, @code{#sysdir}, et cetera,
@vindex msgdir
@vindex sysdir
at drive @code{B:} rather than
drive @code{A:}.
@item
Now here's the trick: rename the Fnordadel binaries from @code{.tos} to
@file{.prg} extensions.
@item
When you boot from disk ``A'' and run @code{citadel}
@sc{gem} will
pop up that familiar ``Insert Disk B into Drive A'' box, and off you go!
Fnordadel will work as normal; the computer will see the data files as
being on drive B:, but that's fine by us.
@end enumerate
A word of caution:  Many a
Sysop employing this technique has come home to find his @sc{bbs} frozen at a
``Please insert Disk A into Drive A'' box.  Make sure that all the directories
your system needs during normal operation start with @code{B:\@dots{}}
rather than
@code{A:\@dots{}}.  This includes system file directories in
@file{ctdlcnfg.sys}, directories
attached to directory rooms, pathnames of files used to archive rooms, etc.

Also note that using this trick requires naming all Fnordadel
programs that you intend to use (@file{citadel.tos}, @file{configur.tos},
utilities) with
the @file{.prg} extender.  Unfortunately,
a side-effect is that you can no longer
supply any command-line parameters to these programs.  Some of the
third-party @sc{gem} enhancements/replacements referred to above may solve
this problem
by letting you have a parameter dialogue box for use with @code{.prg} programs
as well as @code{.ttp} ones.  Also, Double Click is rumoured to have
released a neat hack to allow passing parameters to @code{.prg} programs.

If you do run Fnordadel from the desktop, be warned that you're
missing out on some stuff.  The primary thing is that the desktop has no
way of catching return codes from programs.  (Programs on the ST may return
an integer exit value to the calling program; it's a way of indicating
@pindex citadel
error conditions and stuff.)  @code{citadel} makes use of return codes to tell
you why it is exiting; see also @ref{Events}.

The bottom line, then, is that while you can hack your way into
increased functionality when trying to use Fnordadel from the @sc{gem} Desktop,
you won't ever be able to fully exploit the system's capabilities until you
start using a command shell of some kind.  If you're interested in doing so,
read on.

@node Running from a Shell,  , Running from the Desktop, Shells vs. the Desktop
@section Running from a Shell
@cindex Shell, running Fnordadel from
@cindex Running from a shell
@cindex CLI, running Fnordadel from

If your system has a hard disk, using a shell is highly recommended.
One reason for this is the concept of the ``path'', a list of
directories you define that
tells the shell where to look for programs that you wish to execute.  Thus
you don't have to know which directory a program is in to run it, as long
as the directory is on your path.  Some @sc{gem} enhancements/replacements offer
a similar function (e.g. Hotwire), but you have to set things up a program at
a time, and then call them using ``hot-keys'' from the Desktop.  Is
it easier to
remember to press @code{Control-Alt-F7} to run
@code{citadel}, or to simply type @samp{citadel}
and hit return?

If you've got only floppies, we still recommend using a shell,
especially if you have 1MB or more of @sc{ram}.  (If you have 512K of @sc{ram}, get an
upgrade; they're cheap and you'll be glad you did.)  It will make life
easier.  Both Fnordadel developers are fans of the public domain @code{gulam}
shell.  It's what we use full-time; our systems auto-boot straight into
@code{gulam}, so about the only time we see the @sc{gem} Desktop is if
@code{gulam} crashes.
Fortunately, that's rare.  If you want a copy of @code{gulam}, let us
know and we can supply you with one, or just ask around your local area---it's
everywhere.

There are many reasons to use a shell to run Fnordadel.
Some were mentioned above:  to supply more parameters to programs;
to avoid parameter conversion to upper-case (although some shells
do this too, notably @code{pcommand} and @code{command.tos}); to avoid
having @sc{gem}
erase the output of a program before you can see it; etc.  A further
benefit of @code{gulam} is that it has a built-in version of
the powerful microEmacs
text editor, which is very handy for people who frequently edit
text files.

However, we think the main reason you'll want to use a shell
to run Fnordadel is that shells can catch the values returned by
programs and, with most shells, can be setup to do different things
depending on which code was returned.  You'll want to use this in
conjunction with events (@pxref{Events}), because each event causes
Fnordadel to exit with a different specific code.  You'll also
want to use this even if you have no events defined, because
@pindex citadel
@code{citadel} itself uses a few result codes to indicate different
exit conditions.

We have included a sample gulam shellscript called @file{bbs.g} in
the distribution.  It's for
managing the overall operation of your system; to start up
your @sc{bbs} with it, simply edit it as required, put it somewhere
pointed to by your @code{PATH}, and type @samp{bbs}.  The script is reprinted
for convenience below:

@example
set continue 1          # 'continue' flag
set oldpath $path       # save the old path and set a new one
set path c:\bin,e:\citmain,e:\citnet,e:\citutil,e:\
cd e:\                  # change directory to where ctdltabl.sys lives

while @{ $continue > 0 @}         # Loop until we set 'continue' to '0'

    if @{ -e ctdltabl.sys @} == 0         # is ctdltabl.sys there?
        configur x                      # If not, reconfigure.
    endif

    citadel +line +ymodem +purge        # run citadel

    if @{ $status == 0 @}                 # Did citadel.tos return '0'?
        set continue 0                  # If so, it was ^LQ from the
        echo 'Normal console termination.'      # Console.

    ef @{ $status == 1 @}                 # Did it return '1'?
        echo 'Performing regular backup...'     # If so, it was a
        cp -R d:\secret\sys g:\backup   # defined Timeout (see the
        cp -R d:\secret\net g:\backup   # Reference Manual and
        cp -R d:\secret\audit g:\backup # ctdlcnfg.doc).
        echo 'Finished.'

    ef @{ $status == 2 @}                 # Did it return '2'?
        set continue 0                  # It crashed. The file 'crash'
        echo 'Something must be buggered.'    # may help explain why.

    ef @{ $status == 3 @}                 # Did it return '3'?
        set continue 0                  # That means someone used ^LQ
        echo 'Somebody took it down from remote.'       # from remote.

    ef @{ $status == 255 @}               # Did it return '255'?
        set continue 0                  # **BOOM!**  Can try checking
        echo 'Something is REALLY* buggered.'   # 'crash', but....

    ef @{ $status == 15 @}                # Here's another #event! This
        echo 'Exercising the feeping creatures...'     # one is for
        clog -t > d:\secret\library\userlog.sys        # nightly stats
        popular -msb > d:\secret\library\popular.sys   # gathering and
        callstat -c                                    # stuff like
        cp d:\secret\audit\callbaud.sys d:\secret\library # that...
        cp d:\secret\audit\callstat.sys d:\secret\library
    endif
endwhile                        # ....and loop back to the top again.

# if we reach here, it means that something up there set 'continue'
# to '0', meaning we're supposed to quit.
set path $oldpath               # Reset the path we had before
unset oldpath                   # and remove the variable.
# Done!
@end example

Everything in the above script should be pretty much self-explanatory.  Make
sure that @code{path} is set to point at directories
containing your Fnordadel binaries; that way you can type stuff
like @samp{callstat -c} and the shell will find where @code{callstat} lives.
@pindex callstat
If you have another kind of shell, the same principles should apply,
though the mechanics may vary.